Bluetooth LE, Sensors and you


Have a tutorial for your awesome CBT application?
Send it in!

CANBus Triple is equipped with a Bluegiga BLE112 Bluetooth Low-Energy (4.0) Single mode module. BT LE is very different from legacy BT and is not reverse compatible. To explore the services that CANBus Triple provides over BT LE you can try the LightBlue app for iOS or MacOS.

The BLE112 Firmware is open and available here: https://github.com/CANBus-Triple/CBT-BLE112-Firmware

It is written using Bluegiga BGScript. You can find the documentation and SDK here.

Also, this XML document defines all of the available services running on the BLE112.

Services

Serial API over Bluetooth LE

Serial API BT Service
Service: 7a1fb359-735c-4983-8082-bdd7674c74d2
Characteristic: b0d6c9fe-e38a-4d31-9272-b8b3e93d8657

The Bluetooth LE module is connected to the main processor via UART and allows you to send and receive all the same information you would over the USB Serial connection. BT LE is slower than USB so CAN packets send over BT are rate limited. If you want raw CAN packets over BT you should look into using filters provided by the Serial API under 'Set USB Serial Logging Output'.

The best way is to use sensors (explained below) to process the packets into usable information. This information is stored in one of 8 'Sensor' values exposed by the Bluetooth LE module to any connected device.

The CBT Mobile app is BT LE ready. You can also send commands from the app if you wish. Assure you have an Android or iOS device with Bluetooth LE.

PIN Lock

For security the BT module has a pin code. By default this is disabled (Set to 0000) so if you would like to use this function you will need to set a four digit passcode. 

Pin Lock Service
Service: 35e71686-b1c3-45e7-9da6-1ca2393a41f3
Characteristic: 5fcd52b7-4cfb-4095-aeb2-5c5511646baf

Set Pin Lock Service
Service: 35e71686-b1c3-45e7-9da6-1ca2393a41f3
Characteristic: 5fcd52b7-4cfb-4095-aeb2-5c5511646bcf

To set your pin send a four digit numeric code to the 'Set Pin Lock' service detailed above. You can do this from LightBlue, or your own BT LE code/script. Setting the pin will only succeed if you have already authenticated by sending your current pin to the 'Pin Lock Service' or if it was disabled. The CBT comes with the pin lock disabled.

Now once you've selected a pin you will need to send that same pin to the 'Pin Lock Service' on each additional connection to the BT LE module.

To disable the pin lock mechanism:

  • Ensure you've authenticated with your current pin.
  • Send 0000 to the 'Set Pin Lock' service

Sensors

The CANBus Triple includes a middleware class named ServiceCall. This class will periodically dispatch a CAN service call to the network and parse the response. If the CAN packet you want to parse occurs naturally on the network you can capture and parse that as well.

You can store a total of 8 sensors. The sensor config is stored in the CBT eeprom and will persist between resets / power loss.

Xgauge Codes

Each sensor is a group of values that follow the Xgauge specification. This is useful as a lot of Xgauge codes are available online. You can also create your own codes by following the Xgauge coding manual.

Default Sensor Xgauge codes are found in the firmwares Settings.h file if you would like to modify them. These values are written to the EEPROM on first boot only.

To edit the Xgauge codes easily you can use the CANBus Triple App. Once the CBT is connect to the app just navigate to Sensors and you will see the default values:

App Sensor Settings

When the MCU processes a packet and it matches the Xgauge code it will store the computed value in memory and also dispatch it over UART to the BLE112 so that a BT LE client device will be notified of the updated value.

Flashing the BLE112

The CBT features a 'Pass-through' mode that will send all of the data from the USB Serial connection directly to the BLE112. When you enter Pass-through mode by sending the command 0x0802. Or you can send a 1 to this characteristic to enter Pass-Through mode and also place the BLE112 into DFU mode so it is ready to accept the new firmware. This is the recommended method. 

Set Pin Lock Service
Service: 35e71686-b1c3-45e7-9da6-1ca2393a41f3
Characteristic: 5fcd52b7-4cfb-4095-aeb2-5c5511646bcf

Building custom firmware

To get started clone the current firmware found here. To build the firmware you will need to download the Bluetooth Smart Software and SDK under Software Releases. The SDK is only available for Windows.

Assure your firmware has the UART DFU Bootloader enabled in the *.bgproj file. You will need to ensure this line is in the file <boot fw="bootuart" />. See CBT_ble112.bgproj in the firmware repo for reference.

You can open the bgproj file with the BLE SW Update Tool to build the firmware. It will generate a file named out.hex, this is the firmware binary that will be uploaded to the BLE112.

Sending custom firmware

Using the BLE GUI application from the Bluetooth Smart SDK we will send the out.hex file over USB, through the MCU and to the BLE112.

  1. Connect to the CBT via BT LE using LightBlue and send a reset to DFU mode command as outlined above. The Red and Blue LEDs should illuminate.
  2. Open the BLE GUI application.
  3. Find the COM port your CBT is attached to. Here is enumerated as COM3.
  4. Click 'Attach' to connect
  5. Go to Commands -> DFU
  6. Select the UART Bootloader Tab
  7. Click browse and locate your out.hex firmware file
  8. Click the upload button

The GUI will display it's progress as it uploads. Once the upload is complete the first numerical value will equal the second numerical value. Do not stop the processes once it is started.

Reboot your CBT and you're new BLE112 firmware is running!